home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / program / lxtw109.zip / SXTNVIEW.DOC < prev    next >
Text File  |  1996-08-03  |  17KB  |  442 lines
  1.  
  2.  
  3.  
  4.  
  5.          SXTNVIEW.DOC
  6.  
  7.          SXTNVIEW - SXTN Database Viewer Sample Application
  8.  
  9.          The  SXTNVIEW program  is intended as  a sample  application to
  10.          demonstrate  the use of  the DLL interface  functions to access
  11.          the  SXT  databases.  Each  SXT  windows  version provides  its
  12.          specific  DLL (CFTN16.DLL,  CSTN16.DLL, ...) together  with the
  13.          necessary C/C++  header file (CFTNWIN.H, CSTNWIN.H, ...) and an
  14.          import library (CFTN16.LIB, CSTN16.LIB, ...) that can be linked
  15.          to your programs. SXTNVIEW is a very simple application written
  16.          in  Visual Basic with  complete source  code included. SXTNVIEW
  17.          works with all SXT DLL's and demonstrates the access to all SXT
  18.          database types.
  19.  
  20.          To  run SXTNVIEW, the Visual  Basic runtime library VB40016.DLL
  21.          (not included in this package) installed in the \windows\system
  22.          directory  is required. It  is also  necessary to  copy the SXT
  23.          DLL's to the \windows\system directory.
  24.  
  25.          After starting SXTNVIEW you have to select the SXT program type
  26.          and  the database from  the file  dialog box.  Select one *.dbf
  27.          file  that belongs to the project you  want to view. After that
  28.          you  can  view  in two  list  boxes  the  items (functions/data
  29.          types), either  all or only the defined ones, and the filenames
  30.          by pressing  push buttons next to these list boxes. By a double
  31.          click  on an item you get its  location (filename, line number)
  32.          where  it  is defined/  first found.  By  a double  click  on a
  33.          filename you  get a list of all defined items in that file. You
  34.          can  also directly type  the name of  an item  into the 'Search
  35.          for'  text box and start  a search with the  push button. If an
  36.          item  name is in the  search box you can  press the 'Get Called
  37.          Item'  button to retrieve all  items which are  called from the
  38.          item.
  39.  
  40.          Any running  action can be safely stopped by pressing the 'Stop
  41.          Action' button. The system returns to default state.
  42.  
  43.  
  44.          DLL INTERFACE FUNCTIONS
  45.  
  46.          The  following description  is given  for  the CFT  version but
  47.          applies in the same way to all other SXT programs. The user who
  48.          calls  one of these  functions has  to ensure  that the calling
  49.          parameters  are large  enough to hold  the resulting  value. In
  50.          general, the strings should be a minimum of 300 characters long
  51.          (char location[300], char name[300], ...).
  52.  
  53.          Some functionality  is split into a pair of two closely related
  54.          functions,  like cftnGetFirstName()  and cftnGetNextName(). The
  55.          user  has to ensure that  they are called in  a direct sequence
  56.          and  that  there are  no  intermediate calls,  also  from other
  57.          applications.  Otherwise  the results  will  be  incorrect. The
  58.          reason  for the split  of the functionality  is that  it is not
  59.          possible to  determine the amount of memory to hold the results
  60.          of  the function call  in advance  by the  calling function. It
  61.          would have  been possible to grow the memory dynamically during
  62.          search operation by the DLL, return a pointer to the memory and
  63.  
  64.                                         1
  65.  
  66.  
  67.  
  68.          leave  it to the application  to free it after  use. This would
  69.          work  with C  but not  with Visual  Basic or  application macro
  70.          languages like Word Basic and Visual Basic for Applications.
  71.  
  72.          The  return values of all DLL functions  are 101 if successful,
  73.          all other  values mean that something went wrong (e.g. database
  74.          not found, database is not a SXT database, item does not exist,
  75.          out of memory, ...).
  76.  
  77.          Following is a description of the DLL-functions:
  78.  
  79.          LONG  WINAPI cftnGetLocation(LPSTR  dbfname, LPSTR  name, LPSTR
  80.          location);
  81.          Get the location of a specific item, if the return value is 101
  82.          a location for item was found.
  83.            dbfname   the database name
  84.            name      the name of the item
  85.            location  contains     a    string    with    the    location
  86.          (filename<space>line number) of the item
  87.  
  88.          LONG WINAPI cftnGetFirstName(LPSTR dbfname, LPSTR name);
  89.          Get  the  first item  from the  database, must  be  called once
  90.          before cftnGetNextName.
  91.            dbfname   the database name
  92.            name      contains a string with the item name
  93.  
  94.          LONG WINAPI cftnGetNextName(LPSTR dbfname, LPSTR name);
  95.          Get  the  next item  from the  database, must  be  called after
  96.          cftnGetFirstName, as long as the return value is 101 a new name
  97.          is retrieved.
  98.            dbfname   the database name
  99.            name      contains a string with the item name
  100.  
  101.          LONG WINAPI cftnGetFirstDefName(LPSTR dbfname, LPSTR name);
  102.          Get  the first defined item  from the database,  must be called
  103.          once before cftnGetNextDefName.
  104.            dbfname   the database name
  105.            name      contains a string with the defined item name
  106.  
  107.          LONG WINAPI cftnGetNextDefName(LPSTR dbfname, LPSTR name);
  108.          Get  the next defined  item from  the database,  must be called
  109.          after cftnGetFirstDefName, as long as the return value is 101 a
  110.          new name is retrieved.
  111.            dbfname   the database name
  112.            name      contains a string with the defined item name
  113.  
  114.          LONG WINAPI cftnGetFirstCalledItem(LPSTR dbfname, LPSTR caller,
  115.          LPSTR calleditem, LPSTR location);
  116.          Get the  first called item of caller from the database, must be
  117.          called once before cftnGetNextCalledItem.
  118.            dbfname   the database name
  119.            caller      contains a string with the name of the caller
  120.            calleditem    contains a string with the first called item
  121.            location      contains    a   string    with   the   location
  122.          (filename<space>line number) of the item
  123.  
  124.  
  125.  
  126.  
  127.                                         2
  128.  
  129.  
  130.  
  131.          LONG  WINAPI cftnGetNextCalledItem(LPSTR dbfname, LPSTR caller,
  132.          LPSTR calleditem, LPSTR location);
  133.          Get  the next called item of caller  from the database, must be
  134.          called  after  cftnGetFirstCalledItem, as  long  as  the return
  135.          value is 101 a new called item is retrieved.
  136.            dbfname   the database name
  137.            caller      contains a string with the name of the caller
  138.            calleditem    contains a string with the first called item
  139.            location      contains    a   string    with   the   location
  140.          (filename<space>line number) of the item
  141.  
  142.          LONG WINAPI cftnGetFirstFile(LPSTR dbfname, LPSTR filename);
  143.          Get  the  first file  from the  database, must  be  called once
  144.          before cftnGetFirstFile.
  145.            dbfname   the database name
  146.            name      contains a string with the filename
  147.  
  148.          LONG WINAPI cftnGetNextFile(LPSTR dbfname, LPSTR filename);
  149.          Get  the  next file  from the  database, must  be  called after
  150.          cftnGetFirstFile, as long as the return value is 101 a new file
  151.          is retrieved.
  152.            dbfname   the database name
  153.            name      contains a string with the filename
  154.  
  155.  
  156.          THE VISUAL BASIC EXAMPLE 'SXTNVIEW'
  157.  
  158.          Following  is  a short,  incomplete extract  from  the SXTNVIEW
  159.          Visual Basic source code to show some implementation details.
  160.  
  161.          1.  DLL-FUNCTION DECLARATION
  162.          The DLL-functions have to be declared in the following way:
  163.  
  164.          Declare   Function  cftnGetLocation   Lib  "cftn16.dll"  (ByVal
  165.              dbfname$, ByVal searchname$, ByVal location$) As Long
  166.          Declare   Function  cftnGetFirstName  Lib  "cftn16.dll"  (ByVal
  167.              dbfname$, ByVal location$) As Long
  168.          Declare   Function  cftnGetNextName   Lib  "cftn16.dll"  (ByVal
  169.              dbfnam